Einheit 10 — Ändern ohne kaputtmachen

Was du nach dieser Einheit weißt: Du änderst bestehende Workflows, ohne dass Agents ihre Identität, ihre Nachrichtenhistorie und ihre Canvas-Position verlieren — und du kennst die eine Regel, die darüber entscheidet.

Einen Workflow neu anzulegen ist einfach. Einen laufenden Workflow zu ändern, ist die eigentliche Disziplin. Dabei geht es um Dinge, die man erst vermisst, wenn sie weg sind: Agent-IDs, auf die anderswo verwiesen wird, Nachrichtenhistorie, Log-Historie, Canvas-Positionen.

Zwei Werkzeuge, zwei Anlässe

	agent_update	workflow_update
Ändert	genau einen Agent	den ganzen Workflow aus TowelScript
Nutze, wenn	eine Option, ein Name, eine Verbindung	Struktur, mehrere Agents, neue Nodes
Risiko	gering	mittel — siehe unten

agent_update für punktuelle Änderungen

Mit merge_options: true änderst du eine einzelne Option, ohne die anderen anzufassen:

{
  "agent_id": 1901,
  "options": { "prompt_template": "Fasse zusammen: {{ message.payload.text }}" },
  "merge_options": true
}

merge_options nicht vergessen

Ohne merge_options: true werden die Optionen ersetzt, nicht ergänzt. Alles, was du nicht mitgeschickt hast, ist weg. Bei einem Agent mit zwölf Optionen ist das ein teurer Tippfehler.

agent_update kann außerdem:

Parameter	Zweck
name	Agent umbenennen
disabled	Agent vorübergehend stilllegen — nützlich beim Debuggen
source_ids / receiver_ids	Verbindungen umhängen
schedule	Zeitplan setzen
retry_attempts, retry_delay, retry_exponential_backoff	Wiederholverhalten
failure_receiver_ids	Wohin im Fehlerfall — die Fehlerbehandlung aus Kurs 5, Einheit 6
pos_x, pos_y (mit workflow_id)	Canvas-Position
keep_messages_for	Aufbewahrungsdauer von Nachrichten

workflow_update für strukturelle Änderungen

workflow_update kompiliert den Quelltext neu und gleicht den Workflow damit ab:

• Bestehende Agents werden anhand ihrer GUID an Ort und Stelle aktualisiert
• Agents, die im Quelltext nicht mehr vorkommen, werden entfernt
• Verbindungen werden auf den Stand des Quelltexts gebracht

Das klingt harmlos. Der Haken steckt in „anhand ihrer GUID".

Die Regel: die GUID hängt an der Position

TowelScript vergibt Agent-GUIDs deterministisch — abgeleitet unter anderem aus der Position der Node-Deklaration im Flow-Block. Nicht aus dem Namen allein.

Die Folge: Fügst du einen Node in der Mitte ein, verschieben sich alle dahinter. Ihre GUIDs ändern sich. Und workflow_update erkennt sie nicht mehr wieder — es löscht die alten Agents und legt neue an.

Ein Beispiel

Ausgangszustand, drei Nodes:

flow kontaktanfrage {
  node eingang: form { … }          // Agent-ID 1900
  node extrahieren: ai { … }        // Agent-ID 1901
  node anlegen: http.post { … }     // Agent-ID 1902
  eingang -> extrahieren -> anlegen
}

Jetzt soll eine Prüfung dazwischen. Der naheliegende Weg:

flow kontaktanfrage {
  node eingang: form { … }
  node extrahieren: ai { … }
  node pruefen: filter { … }        // ← in der Mitte eingefügt
  node anlegen: http.post { … }
  eingang -> extrahieren -> pruefen -> anlegen
}

Ergebnis nach workflow_update:

Node	vorher	nachher
eingang	1900	1900	✅ erhalten
extrahieren	1901	1901	✅ erhalten
pruefen	–	1903	neu, korrekt
anlegen	1902	1904	❌ gelöscht und neu angelegt

anlegen hat eine neue ID und eine neue GUID. Seine Nachrichten- und Log-Historie ist weg, seine Canvas-Position ebenfalls. In einem Workflow mit zwanzig Nodes trifft das alles ab der Einfügestelle.

Der richtige Weg: hinten anhängen

Die Reihenfolge der Deklarationen muss nicht der Reihenfolge im Fluss entsprechen. Die Reihenfolge steckt in der Verbindungskette — sonst nirgends.

flow kontaktanfrage {
  node eingang: form { … }
  node extrahieren: ai { … }
  node anlegen: http.post { … }     // bleibt an Position 3
  node pruefen: filter { … }        // ← hinten angehängt
  eingang -> extrahieren -> pruefen -> anlegen
}

Ergebnis: anlegen behält GUID und ID. pruefen kommt neu dazu. Die Kette läuft trotzdem eingang → extrahieren → pruefen → anlegen.

Die Merkregel

Neue Nodes ans Ende des Flow-Blocks. Die Reihenfolge lebt in der Verbindungskette, nicht in der Deklarationsreihenfolge.

Das sieht beim Lesen weniger schön aus — die Kette am Ende sagt aber ohnehin klarer, was passiert, als die Reihenfolge der Blöcke. Und es ist der Unterschied zwischen einem sauberen Update und einem halben Workflow, der neu angelegt wird.

Wie du das vorher siehst

towelscript_compile gibt zu jedem Agent die GUID aus. Vergleiche sie mit denen aus workflow_show, bevor du updatest:

„Kompiliere den geänderten Quelltext und vergleiche die Agent-GUIDs mit denen des deployten Workflows 134. Welche Agents würden neu angelegt?"

Alle GUIDs, die sich unerwartet unterscheiden, sind Agents, die verloren gehen.

📸 Screenshot: [Platzhalter — GUID-Vergleich: compile-Ausgabe neben workflow_show, geänderte GUIDs hervorgehoben]

Zwei weitere Stolperstellen

name und description werden zurückgesetzt

workflow_update ohne name benennt den Workflow in „Workflow" um. Ohne description wird die Beschreibung geleert.

Gib beide bei jedem Update mit:

{
  "workflow_id": 134,
  "source": "module academy …",
  "name": "Kurs 6 | Kontaktanfrage aus Freitext",
  "description": "Nimmt einen E-Mail-Text entgegen, extrahiert den Absender per KI und legt ihn in der Kontakt-API an."
}

Das Canvas-Layout überlebt ein Update nicht immer

Agents, die ihre GUID behalten, behalten auch ihre Position. Neu angelegte Agents landen auf dem Standardplatz. Nach einem strukturellen Update lohnt ein Blick in den Designer.

Die sichere Änderungsroutine

1. workflow_export           → aktuellen Stand sichern
2. Quelltext ändern          → neue Nodes ans Ende
3. check / compile / graph   → Syntax, Optionen, Kanten
4. GUIDs vergleichen         → wer würde neu angelegt?
5. workflow_update           → mit name UND description
6. workflow_show             → sources/receivers gegenprüfen
7. message_reemit            → mit echten Daten nachtesten

Bei größeren Umbauten ist der noch sicherere Weg: workflow_duplicate, am Duplikat arbeiten, und erst umschalten, wenn es läuft.

Versionierung

Weil TowelScript Text ist, gehört er in ein Git-Repository — genau wie in Modul 3, Einheit „Versionsverwaltung mit Git" beschrieben, nur dass du hier die Quelle versionierst und nicht den Export.

Ein bewährter Aufbau:

workflows/
  kontaktanfrage.towel
  rechnungseingang.towel
  exports/
    kontaktanfrage-2026-09-19.json
  CLAUDE.md

In die CLAUDE.md gehören die Regeln, die du nicht jedes Mal wiederholen willst — zum Beispiel: immer check/compile/graph vor dem Deploy, neue Nodes ans Ende, name und description bei jedem Update, vor dem Löschen exportieren.

Zusammengefasst

Regel	Warum
Neue Nodes ans Ende des Flow-Blocks	GUIDs hängen an der Deklarationsposition
Reihenfolge nur in der Verbindungskette ausdrücken	Sie ist die einzige Quelle für den Ablauf
GUIDs vor dem Update vergleichen	Zeigt vorher, welche Agents verloren gehen
name und description immer mitgeben	Sonst heißt der Workflow „Workflow"
merge_options: true bei agent_update	Sonst werden alle anderen Optionen gelöscht
Vor dem Update exportieren	Der einzige Rückweg
Quelltext in Git	Was sich geändert hat, steht dann im Diff

Weiter: Übung — Fehlersuche im laufenden Workflow